Night Owl 6/Night Owl's Shareware - PDSI-006 - Night Owl Corp (1990).iso/001a/ozbii22.zip/OZBEXT.DOC

Text File | 1991-12-07 | 31KB | 592 lines

                                   OZBEXT II
                                  Version 2.2
                                  (07-Dec-91)
    An external protocol module for the CompuServe "B" and "BPlus" protocols

                             Copyright(c)1987-1991
                                  Steve Sneed
                              CIS ID# 70007,3574


Welcome to OZBEXT!
------------------

OZBEXT II is an "external protocol module", a program that allows you to add
the CompuServe "B" and "BPlus" file transfer protocols into other communi-
cations programs.  While not designed primarily as such, the program can
also be used as a (limited) stand-alone communications package for accessing
the CompuServe Information Service (CIS).

Popular file transfer protocols such as XMODEM do not function well under
CompuServe's complex packet-switching network.  The KERMIT protocol, while
operational, is very slow on CIS.  CompuServe developed the B/B+ protocols
to provide optimum performance on the network - it is the recomended method
of file transfer when using CIS.

OZBEXT II works with all major commercial and shareware/freeware communications
programs, and can be used with any comm program that can shell out to DOS
without dropping the connection.  On those programs that provide the capa-
bility, OZBEXT II works best when set up as an external protocol callable from
within the program (examples are ProComm Plus, QModem, Boyan and GT-PowerComm.)
A wide range of options, both on the command line and within the program, allow
you to configure the program to match your needs.  The program automatically
matches itself to your existing communications port configuration, meaning you
do not have to worry about setting things like baud rate and parity when
calling the program.

If you want or need the ability to view CompuServe's RLE and GIF graphics,
such as the radar weather maps, CB pictures, stock trends analysis, and the
over 6000 graphics images in the Graphics Forums, you will want to get OZBEXT
II's sister program, OZRLE.  OZRLE provides all the capabilities of this
program plus adds the ability to view, offline or online in realtime, the
available graphics files and displays CIS provides.  In addition, OZRLE
automatically captures images viewed online to a file for later offline
viewing, saving you substantial connect-time charges.  OZRLE supports all major
IBM video hardware types, including Hercules monochrome, CGA, EGA, MCGA, VGA,
and many "Super" VGA cards.  If you need online graphics capability on BBS's
and other services then BBSGIF will fit the bill; it provides all of the online
graphics capabilities of OZRLE but uses the XMODEM-type protocols.


Before we start...
------------------

Please read this documentation completely.  I know you want to get using the
program right away, but taking a few minutes now may well save you time and
money (in connect-time charges) later.  The program is very simple to use,
and for most users' configurations is fully automatic, but an ounce of pre-
vention is worth a pound of cure.  Thanks!

It is assumed throughout this document that you have a good basic under-
standing of DOS commands, batch files and batch file commands, what
"environment variables" are and how to set them.  If this is not the case,
please have a good MS-DOS tutorial book handy in case I use unfamiliar
terminology.

Help for this program is available online in the IBMNew forum on CompuServe.
Many program-specific help files written by SysOp Connie Kageyama are
available in LIBrary 2 of that forum.  Do a "DIR *.HLP" at the "!" prompt
in that library for a list of those files, or do a "BRO/KEY:HELP" at the
same prompt.  The sysops themselves are available to answer questions, and
of course I check the forums daily to help users.



The Legalities...
-----------------

This program is the copyrighted work of its author, Steve Sneed.  All rights
under US copyright law are reserved.  The author hereby grants to private,
noncommercial users of this program a limited license to use, copy and
distribute the program free of charge, as long as:

a) the program and its accompanying files are not modified in any way other
   than changing the "archive format" used to store and transmit the program;

b) no charge is made for any distribution beyond a nominal disk/duplication
   fee; and

c) the distribution of the program is not done by a business, company or
   private entity whose primary business purpose is the distribution of
   public domain and/or "shareware" software, by any means magnetic or
   electronic, for profit.  Specific exclusion of this clause is hereby
   granted by the author to The First Osborne Group (FOG), The Public
   (Software) Library, CompuServe, Inc. and ZiffNet.  This clause does not
   limit distribution by Bulletin Board Systems or other information services,
   and a fee may be charged for such access as long as such fees are not
   charged specifically for this software.

If the program is used for commercial purposes, a license from the author
is required along with payment of a $25 license fee per copy.  Multi-copy
and site licenses are available; contact the author at the address listed
at the end of this document for more information.  "Commercial purposes"
as used above is defined as use by a company or government service or
organization in an official capacity, or use by a company or individual
whereby financial profit is made from such use - for example, a stock broker
who uses the program to aquire ticker information for clients.  Specific
exclusion of this clause is hereby granted by the author to CompuServe Inc.,
Borland International, TurboPower Software, and ZiffNet.  No other rights
are in any way relinqushed by the author, and the author reserves sole right
to grant and administer licensing and distribution.

This software is provided "as-is", without warranty of any kind, including but
not limited to any warranty of mercantibility or suitability for a specific
purpose.  At no time will the author be held liable for any loss or damage,
including loss of data or time, due to any operation or use of this program,
even if the author has been informed of such loss or potential for loss.

"GIF", "GIF Format" and "Graphic Interchange Format" are Service Marks of
CompuServe Inc., an H&R Block Company.


Installing OZBEXT II
--------------------

OZBEXT II generally should be installed in the same location as your comm
program. If you use a hard disk, this means in the same subdirectory.  If you
use more than one comm program with OZBEXT II and have different programs in
different subdirectories, be sure to place OZBEXT II in a subdirectory that is
on your DOS path.

OZBEXT II is distributed on the CompuServe IBMNet forums in .ARC format.  Some
forums (and BBS systems, if that is where you aquired this program) may
re-compile the program files into a different archive format such as the .ZIP
format, or may use a utility like LHARC to create a self-extracting program
archive.  Once you have copied the archive file or self-extractor onto your
disk, you will need to use the appropriate un-arc utility (if not a
self-extractor) to un-arc the program files back to their original runable
state. Utilities for this purpose are available in most forums on CompuServe,
and on nearly every BBS in the world.


Configuring OZBEXT II
---------------------

Configuration of OZBEXT II is very simple.  The program uses a "standard"
internal configuration that will be correct for 90% or better of users.
The program is quite flexible, however; almost any type of special con-
figuration used on CIS is supported by the program, as well as several
options governing the way the program functions or performs.

The following list contains OZBEXT II's nominal configuration.  Only if
your particular configuration differs from this list should you worry
about the various settings available.

* Uses the COM1: serial port/modem.
* Uses the chosen port's existing baud rate, parity and data/stopbits settings.
* Uses full-duplex communications.
* Provides an audible alarm at the end of a protocol transfer.
* Returns to its own internal terminal mode at the end of a transfer.
* Uses the DOS current working directory for storage of downloaded files,
  and looks in the same directory for files to upload.
* On exit, leaves the modem CarrierDetect line high and restores the port to
  the same configuration in which it was found.
* Perform no logging of transfer success.


Setting Options
---------------

If one or more of the above settings does not match your configuration, there
are two possible ways to change things.  The first way is thru setting
variables in the DOS environment.  The second is to use command line parameters
when executing the program.  If you are calling OZBEXT II from a program such
as QModem that wants to see a batch file rather than a free- standing program
to execute, it is simpler to use the command line parameters within the batch
file (saving the DOS environment space for other programs.) Parameters set via
environment variables can be overridden via command line options.

Below is a list of OZBEXT II's environment variable names and the associated
options:
DSZPORT=?
  or
OZPORT=?         Replace ? with your commport number (1 - 4 for PC-compats,
                                                      3P - 8P for MCA machines)
OZPATH=?         Replace ? with the full path to use for up/downloaded files

When using command line parameters, all parameters must begin with either
a dash (-) or a forward slash (/) character.  Parameters that require qual-
ifying information (such as the port selection parameter) must have the
information immediately after the option letter with no space.  At least
one space must separate each parameter.  Below is the list of available
parameter option letters:

C{portnumber}   Select the comport.  If you use COM2, this would be "/C2".
                The default is COM1.  Ports 1 thru 4 are available for PC-
                compatible machines, and ports 1 thru 8 are available on
                PS/2's and other MCA-buss machines.  If using an MCA machine
                with a comm port higher than 2, add a "P" immediately after
                the number (e.g., for com 3 on a PS/2 you would use "/C3P").

If you are using the program as a stand-alone comm program rather than from
within another comm program (and, generally, _only_ when you use it as such),
one other parameter is available to configure the port.  It is:

B{baudrate}     Specifies the baud rate setting at which to open the port.
                Available baud rates are 300, 1200, 2400, 4800, 9600, 19200,
                38400 and 56000.  The default is to use whatever setting the
                port currently holds.

Note that there is no setting for Parity, data bits or stop bits.  OZBEXT
always forces the port to No Parity/8 Data bits/1 Stop bit on startup and
restores the port to it's original configuration on exit.  Why?  The B+
protocol is an 8-bit protocol and requires a full 8-bit data path.  Old
versions of OZBEXT made a "flying switch" to change parameters at the start
of the protocol transfer session if params other than N81 were in use, but
some modems and/or serial ports do not handle this switch properly when data
is streaming into the port.  Setting N81 on entry to the program (when data
is far less likely to be comming into the port) eliminates this problematic
flying switch.



The other available parameters are used to configure the way OZBEXT II works.
They are:

X               Exit OZBEXT II immediately on completion of a protocol
                transfer. The default is to return to OZBEXT II's internal
                terminal mode so you can download more files or navigate to
                another area of CIS.  This option is normally only used when
                the program is being called from within another comm program's
                script file for automatic execution.

J               Log results of all transfers to OZBEXT.LOG.  The file is
                created if it does not exist.  The default is to not log
                xfers; this just allows those that want logging to have it.

D               Drop carrier on exit.  The default is to leave CarrierDetect
                high.  Using this parameter will mean that OZBEXT II will break
                any existing connection on the modem when exiting - not a good
                idea when you are loading the program from within another
                comm package.

N               Turn off the audible alarm normally provided at the end of a
                protocol transfer.  The default is to provide a beeper at
                the end of a proto transfer and wait for a keypress before
                continuing.  When this switch is used, no alarm sounds and
                the program does not wait for the keypress.  (Note: this
                turns off *all* noise, including the system bell when a ^G is
                received.)

Q               Automatically send an XON character on startup.  This param
                is normally only used with the CIS-specific "auto-navigator"
                programs AUTOSIG and TAPCIS, both of which send an XOFF flow
                control command to CIS when shelling out to DOS.

U               Automatically send a Ctrl-U character on startup.  Using this
                parameter means that, on startup of OZBEXT II, the CIS system
                will automatically interrogate OZBEXT for its terminal-type
                and protocol-support capabilities.  This option should be
                used with caution; in a few places that you might call OZBEXT
                II the sending of the Ctrl-U may confuse the CIS system or may
                abort the imput prompt that was waiting when you called OZBEXT
                II.



L               Use a large (block) cursor while in the program.  This can be
                handy for those using the program on a laptop.  Laptop users
                will probably want to use the OZCOLS program to set the display
                colors to a reasonable set for their display type as well.

O               Turns off checking for the Carrier Detect signal from the
                modem during use.  Normally OZBEXT II checks for this signal
                during a protocol transfer and if the signal is lost (for
                example, when the phone line connection is broken due to
                line noise or other problem) the protocol transfer is
                automatically aborted.  Some CIS users are lucky enoough
                to be connected to the network via direct serial link; these
                links are usually a minimal 3-wire connection without CD
                support.  Users so configured should use this switch; do
                not use this switch if you connect to CIS via modem unless
                you experience problem initiating a transfer.

F{path}         Tells OZBEXT II to put all downloaded files in the {path}
                drive and/or subdirectory, and to take all uploaded files
                from that same location.  OZBEXT II verifies that the specified
                path does exist and if it does not notifies you of the error
                and reverts to the current DOS working directory.  Note that
                you can override this path by including any desired path with
                the filename when answering the "Filename for your computer:"
                prompt from CIS right before beginning the transfer.


Running OZBEXT II
-----------------

OZBEXT II is simple to use.  Depending on what general communications software
you use, it can be made almost automatic.  Due to the wide range of different
communications programs available, no one setup will always be right for
your particular configuration.  However, following these guidelines will make
using the program simple and straightforward.

1)  If your comm program supports it, always install OZBEXT II as an external
    protocol module.  Some programs or versions of programs do not support
    defined external protocol modules but do allow the definition of external
    programs (like editors.)  If this is true for your software, use that
    type of setup.  Only use OZBEXT II from a "general" DOS shell if your soft-
    ware provides no other support for external programs.  Installing OZBEXT II
    as an external protocol module means calling OZBEXT II will be done in the
    same manner as all other protocols, giving you a consistant interface.

2)  If your program requires batch files for external protocol modules (ala
    QModem and a few others), do all parameters options on the batch file
    command line.  Here is an example batch file for QModem:

    ECHO OFF
    CLS
    OZBEXT /c2 /fA:\DNLD\TODAY
    CLS

    This type of setup is also recommended if you use the program from a
    "plain" DOS shell or from within AutoSIG or TAPCIS, or if you run the
    program standalone.

3)  If your communications program is like Boyan (where you can call the
    program directly), it is better to use environment variables to set
    any needed options.  This is best done in your AUTOEXEC.BAT file so
    that the variables are always set.  Programs like Boyan make it easy
    to set a single configuration but make it difficult to modify that
    configuration for special cases; make your setup flexible.

4)  In all the above cases, note that unlike most other protocol modules
    OZBEXT II does not distingush between upload and download on the command
    line.  This is handled at the start of a protocol transfer by the protocol
    itself.  Therefore, you generally only need one configuration for both
    the upload and download entries in your comm program.  However, a tip here
    is that if you use different subdirectories for storing downloads and
    finding uploads, you can set up separate configurations with different
    paths on the /F option on the command line (either batch file or direct
    command methods), or set an environment variable for the files path for
    downloads and override it with a command line setting in the upload setup.

5)  Some programs (like Boyan) allow you to set the amount of memory available
    for a DOS shell.  OZBEXT II requires about 85K free memory to run; some of
    the default settings for these programs do not give enough memory for
    OZBEXT II.  If OZBEXT II will not start from within the DOS Shell of
    another program, after making sure you have specified the correct command
    line params be sure to make sure you have enough memory for the program.
    This is my most-frequent support question.



Using OZBEXT II
---------------

Most protocol modules, when executed, immediately enter the protocol itself.
The B protocols do not work this way.  CIS sends a special interrogation
sequence to the remote system (you) to make sure the remote can in fact do
B and/or B+ before initiating the protocol itself.  OZBEXT II _must_ be loaded
and running to reply to this interrogation properly, or you may well not be
able to do the transfer.  (This is not a deficiency, it is a safety mechanism
for both CIS and you.)  Many places on CIS where you can transfer files, this
interrogation may not be done immediately prior to the protocol initiation;
often it is done when you first request a transfer but before CIS has asked
you for the filename to process and the file type (binary or ASCII.)  Because
of this you should call OZBEXT II _before_ you request the transfer.  OZBEXT II
comes up in terminal mode so that you can answer any pending prompts, etc.

Usually, when you shell out to OZBEXT II from another comm program, there is
a prompt from CIS pending input.  There is no way OZBEXT II can know what this
prompt was and therefore redisplay it (or anything else that was on the screen
when you called it) so you must remember what the prompt was and reply to
it after OZBEXT II is operational.  This is no problem; just type in what you
would have had you been sitting at the prompt.  CIS never sees OZBEXT II load
so it never knows you were not able to see the prompt.

Some users have noted that they "forget I'm in OZBEXT II rather than my main
program."  OZBEXT II provides a status line at the bottom of the screen at all
times to remind you.  I have tried to make sure it does not resemble too
closely the status lines provided by many other comm programs, to make this
recognition easier.   An added tip here is to use the OZCOLS utility program to
set the colors used by OZBEXT II do some set different from your main program.


Commands Within OZBEXT II
-------------------------

OZBEXT II provides several commands while operational.  These all are used to
modify the same functions you set with command line options or environment
variables.  Generally, the letter used for a particular option setting in the
list above will be the key used with the [Alt] key to modify that option while
in OZBEXT II. To see a menu of available Alt-Key commands in the program, press
the [Home] key.  One extra command is available, however: Alt-X is used to exit
the program.



CIS Protocols
-------------

There are three distinct species of B protocol supported by CIS: "Classic" B,
"Quick" B and B Plus.  Most CIS users know that Classic B is the old (and slow)
version of the protocol, but there seems to be a large amount of misconception
concerning QuickB versus BPlus; many users assume that QuickB is faster than
BPlus and therefore preferred (I guess because of the "Quick" in the name.)
This is incorrect.  QuickB and BPlus use almost exactly the same core
procedures to perform the transfer, and under nominal conditions the two will
post identical or nearly identical transfer times.  What BPlus adds is
flexability and safety, by adding features such as Aborted Transfer Resume and
better file management including file information transfer at protocol start,
and more flexible protocol packet size.  BPlus is always the preferred version
to use.

Note that in many areas of CIS where a menu is displayed for protocol type,
only the "B" and "QuickB" types are listed.  Both QuickB and BPlus are designed
to negotiate the actual protocol type level during the protocol startup
handshaking, but some early QuickB implementations (not this program) did not
properly handshake the type - CIS accomodated these ill-behaved programs by
making the QuickB option available in transfer menus.  However, when using this
program, you should always respond with "B" at such a menu so that OZBEXT can
properly handshake the negotiation with the host; selecting "QuickB" at such a
menu forces QuickB mode from CIS and will cause problems when attempting to
resume an aborted transfer as well as locking OZBEXT II into the 512-byte
packet size (rather than the optimal 1024-byte size at 2400bps.)


Protocol Performance
--------------------

Another common misconception is that packet size has a large effect on protocol
performance.  It does indeed effect performance, but not in the way most folks
assume.  The difference in performance at 2400bps between 512-byte packets and
1024-byte packets is seldom more that 3% (unless network loading is heavy) *if*
no transmission errors occur.  In the face of protocol errors where packets
must be resent, smaller is often better because less time is wasted resending
data.  The total size of the transfer, number of errors, network type and
network loading factors cloud the issue, to the point that meaningful
comparisons are quite difficult to achieve.  OZBEXT II juggles default packet
size based on the current baud rate - 128 bytes for 300 baud, 512 bytes for
1200bps and 1024 bytes for 2400bps.  This strikes a reasonable balance between
optimal thruput with no errors, and resend time in case of errors; each packet
will take 4 to 5 seconds to send/receive at the current baud rate.  Some BPlus
implementations lock the packet size at some value, usually 512 bytes.
Sometimes this is for simplicity's sake, and sometimes because there are
factors besides file transfer thruput to be considered (CompuServe's
Information Manager is an example of the latter.)  OZBEXT II has been designed
with one thought in mind: do everything it can to get the highest possible
thruput during the file transfer.  It has proven to be consistently as fast or
faster than any other program available that supports the QuickB and BPlus
protocols, including CIS' own programs.



Users that are used to the transfer rates seen when connected to BBS systems
are oftem shocked and disappointed at the transfer rates seen on CIS.  Keep in
mind that, when connecting to a PC-based BBS, you are connecting to a system
where the entire resources of the computer can typically be devoted to
processing the protocol; such systems can on a clean connection turn optimal
transfer rates for the baud rate used.  CIS is not a BBS; it is a group of
several large computers sharing processor and system resources amomg dozens
or even hundreds of users at any given time.  In order to allow access by all
these people all over the world, CIS uses a special network of phone lines and
satelite links called a "packet-switched" network.  The packet switcher is what
makes all of this possible, but it also introduces delays in communications, so
the typical transfer rate to/from CIS is often lower than a comparable transfer
to/from a dedicated BBS.  The B series protocols have been designed with these
delays in mind, so a QuickB or BPlus transfer should show a very close to
optimal rate under light to moderate network loads.  When network loads are
heavy (such as early weekday evenings, especially Mondays), performance can
still drag down.  Also, connecting thru a supplimental carrier such as Tymnet
can effect performance, as can connecting thru a busy node with several other
users.  If you are concerned with the time you spend online to CIS and have
large and/or many files to transfer, it behooves you to plan your session ahead
of time, including running the session during off-peak times like the small
hours of the morning or weekends.  Taking advantage of OZBEXT II's resumable
transfers, by aborting the download and trying again at a different time or
thru a different node when you see that network delays are seriously slowing
the transfer, can also save you time and money.


The Protocol Window
-------------------

Long-time users of OZBEXT will note this new version has a completely new
protocol status window.  It is both more informative and (I think) easier to
read.  One thing was removed: the separate figures for "raw" and "data"
thruput, which had proven over time to be confusing to a large number of
users.  The CPS and Efficiency reports displayed are for "data" thruput.


Resuming Aborted Transfers
--------------------------

The B+ protocol can resume a download that was aborted due to connection
drop, user request, or other reasons.  When a protocol download is started
and OZBEXT sees that a file of the requested name already exists, it will
prompt you for what to do next.  You can:

*  Resume the transfer.  OZBEXT will then handshake with the CIS host a CRC
   calculation on the file as it exists on your system and the length of that
   file.  The CIS host then sees if the file *it* has is at least as long as
   the one on your machine and has the same CRC for the requested length; if
   both of these parameters match, the transfer is resumed at the point of
   abort.  If either parameter does not match, the transfer begins anew.
   Note that starting with this version, if a resume is attempted and the
   check process fails, OZBEXT automatically renames the download file with a
   dollar sign ($) as the first character of the file name - this prevents an
   important file that happened to be named the same as your download from
   being overwritten.

*  Overwrite the transfer.  OZBEXT replace the existing file with a complete
   new one without attempting to resume the transfer.  No renaming is
   performed.

*  Rename the transfer.  OZBEXT will prompt you for a new name for the file.

*  Abort the transfer.  OZBEXT will stop the transfer cleanly and return to
   terminal mode.



Kudos, Credits, Karma Enhancements
----------------------------------

The sysops of the IBMNet forums on CIS: Don Watkins, Connie Kageyama, Chris
Dunford and Vern Buerg.  My primary beta testers, and the greatest group
of folks around.  Ditto for Valerie Zen and Tom Potoki, sysops of the Graphics
Forums on CIS, who also help test.

Kim, Brian, Rich and Terry (especially Terry) of TurboPower Software, for
writing and maintaining the best libraries of Turbo Pascal utility routines in
the free world.  I feel very lucky to call TurboPower Software my working
home.

Russ Ranshaw ("Wiz10") and others at CIS, for providing exellent documentation
on the B+ protocols, and understandable source code for same.  Ditto to Brion
Jones of CIS for informative literature on interrogation/response sequences
and terminal reply codes.

Most importantly... you, the users.  Your questions, criticisms and sugges-
tions have helped make the program what it is.  If you like it thank yourself,
not me.


Point of Contact
----------------

I can most easily be reached via CompuServe at ID# 70007,3574.  Please leave
questions in either IBMNEW or IBMCOM rather than EasyPlex; other users or the
sysops may well be able to give you a faster answer.  If you need to contact
me concerning registration, please do so by EasyPlex or US mail:

Steve Sneed
CIS ID# 70007,3574
14150 Gleneagle Dr.
Colorado Springs, CO.  80921

This program is not shareware in the traditional sense; I do not require
private non-commercial users to register or pay a license fee (see the section
on license requirements at the top of this document.)  If you have a burning
urge to send me money anyway... I won't turn it down. <grin>  Please make
checks payable to Steve Sneed.  Updates are only done thru CIS; I do not
notify users of updates (except for fully-licensed commercial users.)  If
you are registering for full license, please plainly state so in your
corospondence along with how you are using the program.  Site licenses and
multi-license discounts are available; please contact me for specific info.
Finally, please do not call me voice, and I cannot accept any collect calls.
Thanks.

I hope you enjoy the program!

<eof>